OpenHIM
OpenHIM (Open Health Information Mediator) is the reference implementation of the OpenHIE interoperability layer. It sits between point-of-service systems and the registries and domain services behind them, handling authentication, routing, transaction logging and orchestration.
- Tier 2 · MPL 2.0 · Node.js · https://openhim.org/
- Source: https://github.com/jembi/openhim-core-js
What it provides
| Capability | How |
|---|---|
| Client authentication | Registered clients with basic auth, mutual TLS or token; each with distinct roles |
| Routing | Channels match incoming requests by URL pattern and method and forward to one or more routes |
| Transaction log | Every request and response persisted, searchable in the console, with replay |
| Mediation | Mediators — separate services that transform, orchestrate and enrich |
| Orchestration | A mediator can call several services and record each call against the parent transaction |
| Monitoring | Console with transaction volumes, error rates and per-channel status |
| Replay and rerun | Failed transactions can be re-sent after the downstream fault is fixed |
| Alerting | Notification on failure thresholds |
The transaction log with replay is the feature that most distinguishes it in practice. When a downstream registry is down for two hours, the operational question is which transactions failed and can they be re-sent — and OpenHIM answers it directly rather than requiring log archaeology.
Channels and mediators
Point-of-service system
│ POST /fhir/Patient
▼
┌────────────────────────────────────────────┐
│ OpenHIM core │
│ · authenticate client │
│ · match channel by URL pattern │
│ · authorise by role │
│ · persist transaction │
└───────────────┬────────────────────────────┘
│ route
▼
┌────────────────────────────────────────────┐
│ Mediator (separate service, any language) │
│ · validate against profile │
│ · resolve identity via client registry │
│ · translate codes via terminology service │
│ · write to shared health record │
│ · report orchestrations back to core │
└───────────────┬────────────────────────────┘
▼
Registries · SHR · HMIS
Channels are configuration: which URL patterns are accepted, from which clients, forwarded where, with what authorisation. They live in the OpenHIM console and are exportable as configuration.
Mediators are independent services that register themselves with the core. They can be written in any language; the OpenHIM project provides scaffolding libraries for several. A mediator reports its orchestrations — the downstream calls it made — back to the core, so a single transaction view shows the whole chain.
That separation is the design's strength: the core stays generic and stable, while integration logic is developed, deployed and retired per use case without touching it.
Where it fits
OpenHIM is the implementation of one component of the OpenHIE reference architecture. It is not itself an architecture, and deploying it does not produce interoperability — it produces a place to put the routing and audit that interoperability requires.
Adjacent components it typically fronts:
- Client registry (OpenCR, SanteMPI)
- Facility registry
- Health worker registry
- Terminology service
- Shared health record — usually HAPI FHIR
- DHIS2 as the HMIS
The OpenHIE community also publishes Instant OpenHIE, a packaged deployment that stands several of these up together for evaluation and development. It is useful for demonstrating an architecture quickly; it is not a production configuration.
Operating it
Things to plan for before it carries clinical traffic:
Availability. Once every system routes through it, an outage stops all exchange. Run more than one instance, health-check them, and ensure point-of-service systems queue locally rather than dropping data.
Transaction log growth. Persisting every request and response, including bodies, grows quickly — and those bodies contain personal health data. Configure retention, restrict access to the console, and treat the log store as clinical data for backup and encryption purposes.
Console access. The console can display transaction bodies, which means console access is access to patient data. Restrict it, log it, and do not share administrator accounts.
Mediator ownership. Mediators proliferate. Maintain a register: what each one does, who owns it, which version is deployed, and when it was last tested. Unowned mediators are how these deployments decay.
Performance. Body persistence is the usual bottleneck. Consider whether every channel needs full body logging, or whether some can log metadata only — this is a privacy improvement as well as a performance one.
Certificates. Mutual TLS with many clients means many certificates and many expiry dates. Automate renewal and monitor expiry; see security architecture.
Alternatives
OpenHIM is not the only way to implement the interoperability layer.
| Option | Consider when |
|---|---|
| Mirth / NextGen Connect | HL7 v2 traffic dominates and you want a mature graphical transformation environment |
| Apache Camel | Your team is Java-centric and wants integration logic as code with strong testing |
| API gateway + services | You already run Kong/Traefik/Envoy and are prepared to build mediation and transaction logging separately |
| Cloud integration services | You are cloud-committed and data residency permits it |
The features you would have to rebuild if you choose a general-purpose gateway are the transaction log with replay, the orchestration view, and the mediator registration model. Those are not trivial, and their absence is usually discovered during the first production incident.
See integration engines.
References
- OpenHIM — https://openhim.org/
- OpenHIM documentation — https://openhim.org/docs/introduction/about
- OpenHIM core source — https://github.com/jembi/openhim-core-js
- OpenHIE architecture — https://ohie.org/
- Instant OpenHIE — https://github.com/openhie/instant